opencard.opt.database
Class BasicDatabase

java.lang.Object
  opencard.core.service.CardService
      opencard.opt.database.BasicDatabase

All Implemented Interfaces:

CardServiceInterface, DatabaseCardService, DatabaseCardService.Constants

public class BasicDatabase

extends CardService

implements DatabaseCardService, DatabaseCardService.Constants

This class is designed as a basic default class which allows programmers to access ISO 7816-7-compliant smartcards.

It provides all methods necessary to access database smartcards, as describes in the ISO 7816-7 norm.

It is intended that the CardService developers for specific card use this class as a base class and by inheriting its functionalities

Since:

OCF1.2

See Also:

DatabaseCardService

Nested Class Summary

Nested classes inherited from class opencard.opt.database.DatabaseCardService

DatabaseCardService.Constants

Field Summary

protected int

MAX_SIZE MAX_SIZE represents maximum size of a command APDU that can be built.

Fields inherited from interface opencard.opt.database.DatabaseCardService.Constants

BEGIN, COMMIT, CREATE_DICTIONARY, CREATE_TABLE, CREATE_USER, CREATE_VIEW, DECLARE_CURSOR, DELETE, DELETE_USER, DROP_TABLE, DROP_VIEW, EQUAL_TO, FETCH, FETCH_NEXT, GRANT, GREATER_THAN, GREATER_THAN_OR_EQUAL_TO, INSERT, LESS_THAN, LESS_THAN_OR_EQUAL_TO, NEXT, NOT_EQUAL_TO, OPEN, PRESENT_USER, PRIV_ALL, PRIV_DELETE, PRIV_INSERT, PRIV_SELECT, PRIV_UPDATE, REVOKE, ROLLBACK, SCQL_OPERATION, SW1_CHECK_ERROR, SW1_COMMAND_NOT_ALLOWED, SW1_EXEC_ERROR, SW1_INSTRUCTION_CODE_NOT_SUPPORTED, SW1_OK, SW1_OK_WITH_RETURN, SW1_WARNING, SW1_WRONG_LENGTH, SW1_WRONG_PARAM, SW2_CHECK_ERROR, SW2_COMMAND_NOT_ALLOWED, SW2_EXEC_ERROR, SW2_INCORRECT_PARAM, SW2_INSTRUCTION_CODE_NOT_SUPPORTED, SW2_MEM_FAILURE, SW2_OBJECT_ALREADY_EXISTS, SW2_OBJECT_NOT_FOUND, SW2_OK, SW2_OPERATION_NOT_SUPPORTED, SW2_REQUIRED_OPERATION, SW2_SECURITY, SW2_WARNING, SW2_WRONG_PARAM, TAG_CH_CERTIFICATE_1, TAG_CH_CERTIFICATE_2, TAG_CH_NAME_1, TAG_CH_NAME_2, TRANSACTION_OPERATION, UPDATE, USER_OPERATION

Constructor Summary

BasicDatabase()
Constructor called when creating a new BasicDatabase.

Method Summary

void	begin() Allocates space for a memory image, e.g.
void	commit() Validates all the modifications made since the transaction operation BEGIN as been executed. The transaction operation BEGIN must have been previously performed.
void	createDictionary(java.lang.String dictionary) Defines a view on the system tables *O, *U and *P.
void	createTable(java.lang.String tableName, java.lang.String columnsList, byte maxNumberOfRows, SecurityAttribute securityAttribute) Defines a table with its columns and possibly with security attributes.
void	createTable(java.lang.String tableName, java.lang.String columnsList, SecurityAttribute securityAttribute)
void	createUser(java.lang.String userID, java.lang.String userProfile, SecurityAttribute securityAttribute) Initiates the registration of a user.
void	createView(java.lang.String viewName, java.lang.String tableName, java.lang.String colunmNames, java.lang.String conditions, SecurityAttribute securityAttribute) Defines a view on a table.
void	declareCursor(java.lang.String objectName, java.lang.String columnsName, java.lang.String conditions) Cursor is used for pointing to a row on a table, view or dictionary.
void	delete() Deletes a row in a table to which the cursor points.
void	deleteUser(java.lang.String userID) Allows a user to be deleted.
void	dropTable(java.lang.String tableName) Allows to drop a table. A table can only be dropped by its owner.
void	dropView(java.lang.String viewName) Allows to drop a view. A table can only be dropped by its owner.
java.lang.String[]	fetch() Allows to fetch a row or part of it.
java.lang.String[]	fetch(byte maxLength) Allows to fetch a row or part of it.
java.lang.String[]	fetchNext() Used for reading the logical next row from the cursor position.
java.lang.String[]	fetchNext(byte maxLength) Used for reading the logical next row from the cursor position.
void	grant(java.lang.String privileges, java.lang.String objectName, java.lang.String userID) Allows to grant privileges to a single user, to a user group or to all users.
protected void	initialize(CardServiceScheduler scheduler, SmartCard smartcard, boolean blocking) Allows to initialize the cardservice.
void	insert(java.lang.String tableName, java.lang.String values) Used to insert a row in a table.
static boolean	knows(CardID cid, CardServiceScheduler sched) A static method to analyze a smartcard in order to determine if it is an SCQL card, i.e., compliant with the ISO7816-7 standard.
void	next() Sets the current cursor on the next row satisfying the cursor specification. A cursor must have been opened before.
void	open() Opens a cursor, i.e., the cursor is positioned on the first row which satisfies the selection previously defined with the declareCursor method.
void	presentUser(java.lang.String userID)
void	presentUser(java.lang.String userID, SecurityAttribute securityAttribute) Checks the presented user id.
void	revoke(java.lang.String privileges, java.lang.String objectName, java.lang.String userID) Allows to revoke privileges granted before. Only the owner of the table or view can revoke privileges.
void	rollback() Restores the context in the way it was before the transaction operation BEGIN as been executed. The transaction operation BEGIN must have been previously performed.
protected ResponseAPDU	sendAPDU(CommandAPDU cmd) This method is used to send APDU commands to the smartcard.
protected void	throwException(ResponseAPDU apdu) This method is used in this package to manage exceptions.
void	update(java.lang.String values) Updates one or more fields of a row in a table or view to which the cursor points. The command can only be executed by the table owner or a user with the UPDATE privilege. A cursor must be opened before. The value for the special column USER, if present, is inserted by the card.

Methods inherited from class opencard.core.service.CardService

allocateCardChannel, getCard, getCardChannel, getCHVDialog, releaseCardChannel, setCardChannel, setCHVDialog

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface opencard.opt.service.CardServiceInterface

getCard, setCHVDialog

Field Detail

MAX_SIZE

protected final int MAX_SIZE

MAX_SIZE represents maximum size of a command APDU that can be built.

See Also:

Constant Field Values

Constructor Detail

BasicDatabase

public BasicDatabase()

Constructor called when creating a new BasicDatabase.

Method Detail

initialize

protected void initialize(CardServiceScheduler scheduler,
                          SmartCard smartcard,
                          boolean blocking)
                   throws CardServiceException

Allows to initialize the cardservice. This method is called when instanciating the cardservice (after the call of the BasicDatabase constructor).

Overrides:

initialize in class CardService

Parameters:

scheduler - The CardServiceScheduler.

smartcard - The SmartCard.

blocking - Boolean that defines if the smartcard blocks access for other applications while working or not.

Throws:

CardServiceException - if the service could not be initialized. The object created via the default constructor may not be used if this happens.

See Also:

BasicDatabase()

createTable

public void createTable(java.lang.String tableName,
                        java.lang.String columnsList,
                        byte maxNumberOfRows,
                        SecurityAttribute securityAttribute)
                 throws SCQLException

Defines a table with its columns and possibly with security attributes. The table definition is added in the object descriprion table.

A table can only be created by users with the DB_O profile (DataBase Owner) or DBOO (DataBase Object Owner).

Specified by:

createTable in interface DatabaseCardService

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String, java.lang.String, java.lang.String, java.lang.String, byte);, (java.lang.String)

createTable

public void createTable(java.lang.String tableName,
                        java.lang.String columnsList,
                        SecurityAttribute securityAttribute)
                 throws SCQLException

Throws:

SCQLException

createView

public void createView(java.lang.String viewName,
                       java.lang.String tableName,
                       java.lang.String colunmNames,
                       java.lang.String conditions,
                       SecurityAttribute securityAttribute)
                throws SCQLException

Defines a view on a table. The view definition is added to the object description table.
A view can only be created by the owner of the referenced table.
If several conditions are present, they are implicitely combinated with a logical AND.

Specified by:

createView in interface DatabaseCardService

Parameters:

conditions - The list of conditions used to build the view. Each field is separed from the next by a coma.

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String, java.lang.String, byte, byte), (java.lang.String)

createDictionary

public void createDictionary(java.lang.String dictionary)
                      throws SCQLException

Defines a view on the system tables *O, *U and *P. The fixed view definitions are added by the card in the object descrition table.
A dictionary can only be created by the DB_O (DataBase Owner) or a DBOO (DataBase Object Owner).

Note : This command has no equivalence in SQL.

Specified by:

createDictionary in interface DatabaseCardService

Parameters:

dictionary - The name of the dictionary you want to create.

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

opencard.opt.database.BasicDatabase#createTable(java.lang.String, java.lang.String ,byte, byte), (java.lang.String, java.lang.String, java.lang.String, java.lang.String)

dropTable

public void dropTable(java.lang.String tableName)
               throws SCQLException

Allows to drop a table.
A table can only be dropped by its owner. The privileges associated to the table should be automatically be dropped.

Specified by:

dropTable in interface DatabaseCardService

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String)

dropView

public void dropView(java.lang.String viewName)
              throws SCQLException

Allows to drop a view.
A table can only be dropped by its owner. The privileges associated to the table should be automatically be dropped.

Specified by:

dropView in interface DatabaseCardService

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String)

grant

public void grant(java.lang.String privileges,
                  java.lang.String objectName,
                  java.lang.String userID)
           throws SCQLException

Allows to grant privileges to a single user, to a user group or to all users.

The following rivileges may be granted.

Privileges for table access :

• SELECT
  
• INSERT
  
• UPDATE
  
• DELETE
  
• ALL
  

Privileges for view access :

• SELECT
  
• UPDATE
  

Privileges for dictionary access :

• SELECT
  

Specified by:

grant in interface DatabaseCardService

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String, java.lang.String, java.lang.String), SecurityStatusNotSatisfiedException, IncorrectParameterInDataFieldException, OperationNotSupportedException, ReferencedObjectNotFoundException

revoke

public void revoke(java.lang.String privileges,
                   java.lang.String objectName,
                   java.lang.String userID)
            throws SCQLException

Allows to revoke privileges granted before.
Only the owner of the table or view can revoke privileges.

Specified by:

revoke in interface DatabaseCardService

Throws:

opencard.opt.database.SCQLException#SCQLException()

opencard.opt.database.SCQLException#SCQLException(java.lang.String)

SCQLException

See Also:

(java.lang.String, java.lang.String, java.lang.String), SecurityStatusNotSatisfiedException, IncorrectParameterInDataFieldException, ReferencedObjectNotFoundException

declareCursor

public void declareCursor(java.lang.String objectName,
                          java.lang.String columnsName,
                          java.lang.String conditions)
                   throws SCQLException

Cursor is used for pointing to a row on a table, view or dictionary. This method is used for the declaration of a cursor.
The declaration of the cursor is only accepted if the actual user is authorized to access the referenced table, view or dictionary. The user has to be the owner of the referenced object or at least one privilege for access to the referenced object.
Only one cursor can exist at a given time, i.e., if a new cursor is declared then the previous is no longer valid.

Specified by:

declareCursor in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(), fetch(byte), fetchNext(), fetchNext(byte), open(), next()

open

public void open()
          throws SCQLException

Opens a cursor, i.e., the cursor is positioned on the first row which satisfies the selection previously defined with the declareCursor method.

Specified by:

open in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(), fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), next()

next

public void next()
          throws SCQLException

Sets the current cursor on the next row satisfying the cursor specification.
A cursor must have been opened before.

Specified by:

next in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(), fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open()

fetch

public java.lang.String[] fetch(byte maxLength)
                         throws SCQLException

Allows to fetch a row or part of it. The cursor has to point on the row to be fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege A cursor must have been opened before.

Specified by:

fetch in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetch

public java.lang.String[] fetch()
                         throws SCQLException

Allows to fetch a row or part of it. The cursor has to point on the row to be fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege.
A cursor must have been opened before.
No maximum length of data is expected.

Specified by:

fetch in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(byte), fetchNext(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetchNext

public java.lang.String[] fetchNext(byte maxLength)
                             throws SCQLException

Used for reading the logical next row from the cursor position. The cursor is set to the row being fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege.
A cursor must have been opened before.

Specified by:

fetchNext in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(byte), fetch(), fetchNext(), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

fetchNext

public java.lang.String[] fetchNext()
                             throws SCQLException

Used for reading the logical next row from the cursor position. The cursor is set to the row fetched.
The operation can only be executed by the object owner or a user with the SELECT privilege. A cursor must have been opened before.
No maximum length of data is expected.

Specified by:

fetchNext in interface DatabaseCardService

Throws:

SCQLException

See Also:

fetch(byte), fetch(), fetchNext(byte), declareCursor(java.lang.String, java.lang.String, java.lang.String), open(), opencard.opt.database.BasicDatabase#next(byte)

insert

public void insert(java.lang.String tableName,
                   java.lang.String values)
            throws SCQLException

Used to insert a row in a table. A new row is always added at the end of a table. The cursor remains at its position.
The command can only be executed by the table owner or a user with the INSERT privilege.
The value for the special column USER, if present, is inserted by the card.

Specified by:

insert in interface DatabaseCardService

Parameters:

values - The String that contains the list of values to be inserted.

Throws:

SCQLException

See Also:

update(java.lang.String), delete()

update

public void update(java.lang.String values)
            throws SCQLException

Updates one or more fields of a row in a table or view to which the cursor points.
The command can only be executed by the table owner or a user with the UPDATE privilege.
A cursor must be opened before.
The value for the special column USER, if present, is inserted by the card.

Specified by:

update in interface DatabaseCardService

Parameters:

values - The String that contains the list of values to be updated.

Throws:

SCQLException

See Also:

insert(java.lang.String, java.lang.String), delete()

delete

public void delete()
            throws SCQLException

Deletes a row in a table to which the cursor points. The cursor is moved to the logical next row.
The command can only be executed by the table owner or a user with the DELETE privilege for the referenced table.

Specified by:

delete in interface DatabaseCardService

Throws:

SCQLException

See Also:

insert(java.lang.String, java.lang.String), update(java.lang.String)

begin

public void begin()
           throws SCQLException

Allocates space for a memory image, e.g. a row.
The memory space which is provided is implementation dependent. It is recommended that enough memory space for the buffering of at least one row is allocated.

Specified by:

begin in interface DatabaseCardService

Throws:

SCQLException

See Also:

commit(), rollback()

commit

public void commit()
            throws SCQLException

Validates all the modifications made since the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.

Specified by:

commit in interface DatabaseCardService

Throws:

SCQLException

See Also:

begin(), rollback()

rollback

public void rollback()
              throws SCQLException

Restores the context in the way it was before the transaction operation BEGIN as been executed.
The transaction operation BEGIN must have been previously performed.

Specified by:

rollback in interface DatabaseCardService

Throws:

SCQLException

See Also:

begin(), commit()

presentUser

public void presentUser(java.lang.String userID,
                        SecurityAttribute securityAttribute)
                 throws SCQLException

Checks the presented user id. If the user id is registred in the system table *U, the user characterized by its user id is set as current user.
There can only be one current user at a time per logical channel.

Specified by:

presentUser in interface DatabaseCardService

Parameters:

securityAttribute - the security attribute presented for authentication.

Throws:

SCQLException

See Also:

opencard.opt.database.BasicDatabase#createUser(java.lang.String, java.lang.String, java.lang.String), deleteUser(java.lang.String), SecurityAttribute

presentUser

public void presentUser(java.lang.String userID)
                 throws SCQLException

Specified by:

presentUser in interface DatabaseCardService

Throws:

SCQLException

createUser

public void createUser(java.lang.String userID,
                       java.lang.String userProfile,
                       SecurityAttribute securityAttribute)
                throws SCQLException

Initiates the registration of a user. In a SCQL environment a row in the user description table is inserted by the card.
This command can only be performed by users with profiles DB_O (i.e., DataBase Owner) or DBOO (i.e., DataBase Object Owner) with the right permissions. The user id has to be unique.

Specified by:

createUser in interface DatabaseCardService

Parameters:

securityAttribute - the security attribute presented for authentication.

Throws:

SCQLException

See Also:

opencard.opt.database.BasicDatabase#presentUser(java.lang.String, java.lang.String), deleteUser(java.lang.String)

deleteUser

public void deleteUser(java.lang.String userID)
                throws SCQLException

Allows a user to be deleted. The respective row in the user description table is erased.
This operation can only be performed by the user owner. In order to ensure database integrity, privileges associated to this user should be automatically removed.

Specified by:

deleteUser in interface DatabaseCardService

Throws:

SCQLException

See Also:

opencard.opt.database.BasicDatabase#presentUser(java.lang.String, java.lang.String), opencard.opt.database.BasicDatabase#createUser(java.lang.String, java.lang.String, java.lang.String)

throwException

protected void throwException(ResponseAPDU apdu)
                       throws SCQLException

This method is used in this package to manage exceptions. It analyzes the response sent back by the smartcard and raises the appropriate exception.

Throws:

SCQLException

sendAPDU

protected ResponseAPDU sendAPDU(CommandAPDU cmd)
                         throws SCQLException

This method is used to send APDU commands to the smartcard.

Parameters:

cmd - The APDU command to be sent.

Returns:

The APDU response send back by the smartcard.

Throws:

SCQLException

knows

public static boolean knows(CardID cid,
                            CardServiceScheduler sched)

A static method to analyze a smartcard in order to determine if it is an SCQL card, i.e., compliant with the ISO7816-7 standard. It is not possible here to analyze only the card ATR because the standard does not specify anything about it. On the contrary the following method is applied:

1. a temporary SlotChannel is allocated (using the scheduler),
2. a 'PRESENT USER ("PUBLIC")' command w/o password is sent, and
3. the response is analyzed (it should be 9000 for an SCQL card).

This method complies with the following OCF naming pattern:
"A CardService 'knows' how to recognize supported cards"

Parameters:

cid - the ATR of the smartcard

sched - a CardServiceScheduler for temporary communication

Returns:

true or false